Celestin Apprentice 5

home *** CD-ROM | disk | FTP | other *** search

/ Celestin Apprentice 5 / Apprentice-Release5.iso / Source Code / Libraries / Bitmap Libraries 2.0 / 411 files / BitMapHelp < prev

Wrap

Text File | 1996-03-09 | 40.3 KB | 1,335 lines | [TEXT/MPS ]

æKY CopyrightNoticeBitMapHelp æC ----- BitMapHelp Copyright (c) 1996 by John Montbriand. All rights reserved. æKY BitMap.h BitMapHelp BitMaps æC ----- Routines for working with bitmap pointers. BitMapHelp Copyright (c) 1996 by John Montbriand. All rights reserved. storage managment for bitmaps: NewBitMap -- create a new bitmap pointer KillBitMap -- dispose of a bitmap pointer DuplicateBitMap -- make a duplicate flip and rotate routines: RotateRight -- 90 degrees to the right RotateLeft -- 90 degrees to the left FlipVertical -- flip vertically FlipHorizontal -- flip horizontally RotateBitMap -- rotate to a particular angle paint bucket and lasso routines: PaintBucketBitMap -- paint bucket LassoBitMap -- the lasso special effects: TraceBitMap -- trace the edges of a bitmap image QuickDraw picture transfer functions: PICTToBitMap -- convert a QuicDraw Picture to a bitmap pointer BitMapToPICT -- convert a bitmap pointer to a QuicDraw Picture logical operations: BitMapAND -- logically AND raster data BitMapOR -- logically OR raster data BitMapXOR -- logically XOR raster data BitMapNOT -- logically COMPLEMENT raster data comparison: EqualBitMaps -- compare two bitmaps for equality pixel oriented functions: BitMapTest -- test the value of a particular pixel BitMapSet -- set a particular pixel to the value 1 BitMapClear -- set a particular pixel to the value 0 BitMapToggle -- invert a pixel returning it's new value routines for drawing into bitmaps: NewBMP -- called by WithBitMap to set up a grafport DisposeBMP -- called by WithBitMap to dispose of a grafport WithBitMap -- MACRO for drawing into bitmaps routines for copying bitmap data: PlotBitMap -- copy bitmap data to the current grafport æKY NewBitMap æFc BitMap.h æMM æD BitMap* NewBitMap(short width, short height); æDT BitMap *bits = NewBitMap((short) width, (short) height); æT Function æC ----- for creating a new bitmap pointer. arguments: width the width of the requested bitmap height the height of the requested bitmap return value: a pointer to a Bitmap data structure. if an error occurs, NULL is returned. description: NewBitMap creates a new bitmap pointer with the requested dimensions. The raster data is initialized to zeros, and if there is not enough memory to allocate the bitmap, NewBitMap will return NULL. example application: The following creates a new bitmap pointer 100 pixels wide and 200 pixels tall. { BitMap *the_bits; the_bits = NewBitMap(100, 200); ... notes: You can call DisposePtr to dispose of a bitmap pointer created by NewBitMap. The routine KillBitMap calls DisposePtr. æKY KillBitMap æFc BitMap.h æMM æD void KillBitMap(BitMap* bits); æDT KillBitMap((BitMap*) bits); æT Procedure æC ----- to dispose of the storage occupied by a bitmap pointer. arguments: bits a bitmap pointer return value: none. description: KillBitMap disposes of a bitmap pointer allocated by one of: NewMacPaintBitMap, NewBitMap, RotateRight, RotateLeft, FlipVertical, FlipHorizontal, RotateBitMap, DuplicateBitMap, PaintBucketBitMap, LassoBitMap, PICTToBitMap, BitMapAND, BitMapOR, BitMapXOR, or BitMapNOT. It's your general all purpose bitmap pointer disposal function. example application: The following creates a new bitmap handle 100 pixels wide and 200 pixels tall and then disposes of it by calling KillBitMap. { BitMap *the_bits; the_bits = NewBitMap(100, 200); if (the_bits != NULL) { KillBitMap(the_bits); } notes: KillBitMap simply calls DisposePtr. æKY RotateRight æFc BitMap.h æMM æD BitMap* RotateRight(BitMap* bits); æDT BitMap *round_bits = RotateRight((BitMap*) bits); æT Function æC ----- to rotate a bitmap 90 degrees to the right. arguments: bits a bitmap pointer return value: a newly created bitmap pointer containing the image from the bitmap pointer parameter rotated 90 degrees to the right. if an error occurs, RotateRight will return the value NULL. description: RotateRight creates a new bitmap containing the image stored in the parameter bitmap pointer rotated 90 degrees to the right. The resulting bitmap is appropriately sized: i.e. if the source bitmap is 100 pixels wide and 200 pixels tall, then the result bitmap pointer will be 200 pixels wide and 100 pixels tall. example application: The example creates a new bitmap pointer containing the image stored in the original bitmap rotated 90 degrees to the right before copying the image to the current grafport. { BitMap *the_bits; BitMap *rotated_bits; Rect bounds; the_bits = NewBitMap(100, 200); if (the_bits != NULL) { /* here we would draw something into the_bits */ rotated_bits = RotateRight(the_bits); if (rotated_bits != NULL) { bounds = (*rotated_bits)->bounds; PlotMap(rotated_bits, 0, 0, srcCopy); KillBitMap(rotated_bits); } KillBitMap(the_bits); } notes: RotateRight takes advantage of certain addressing and indexing possibilities offered by the arrangement of the raster data in memory. It is faster than calling RotateBitMap and specifying a 90 degree angle. æKY RotateLeft æFc BitMap.h æMM æD BitMap* RotateLeft(BitMap* bits); æDT BitMap *left_bits = RotateLeft((BitMap*) bits); æT Function æC ----- to rotate a bitmap image 90 degrees to the left. arguments: bits a bitmap pointer return value: a newly created bitmap pointer containing the image from the bitmap pointer parameter rotated 90 degrees to the left. if an error occurs, RotateLeft will return the value NULL. description: RotateLeft creates a new bitmap containing the image stored in the parameter bitmap pointer rotated 90 degrees to the left. The resulting bitmap is appropriately sized: i.e. if the source bitmap is 100 pixels wide and 200 pixels tall, then the result bitmap pointer will be 200 pixels wide and 100 pixels tall. example application: The example creates a new bitmap pointer containing the image stored in the original bitmap rotated 90 degrees to the left before copying the image to the current grafport. { BitMap *the_bits; BitMap *rotated_bits; Rect bounds; the_bits = NewBitMap(100, 200); if (the_bits != NULL) { /* here we would draw something into the_bits */ rotated_bits = RotateLeft(the_bits); if (rotated_bits != NULL) { bounds = (*rotated_bits)->bounds; PlotMap(rotated_bits, 0, 0, srcCopy); KillBitMap(rotated_bits); } KillBitMap(the_bits); } notes: RotateLeft takes advantage of certain addressing and indexing possibilities offered by the arrangement of the raster data in memory. It is faster than calling RotateBitMap and specifying a -90 degree angle. æKY FlipVertical æFc BitMap.h æMM æD BitMap* FlipVertical(BitMap* bits); æDT BitMap *vertical_bits = FlipVertical((BitMap*) bits); æT Function æC ----- to flip a bitmap vertically. arguments: bits a bitmap pointer return value: a newly created bitmap pointer containing the image from the bitmap pointer parameter flipped upside down. if an error occurs, FlipVertical will return the value NULL. description: FlipVertical creates a new bitmap containing the image stored in the parameter bitmap pointer flipped upside down. The resulting bitmap will be the same size as the original image. example application: The example creates a new bitmap pointer containing the image stored in the original bitmap flipped upside down before copying the new flipped image to the current grafport. { BitMap *the_bits; BitMap *flippin_bits; Rect bounds; the_bits = NewBitMap(100, 200); if (the_bits != NULL) { /* here we would draw something into the_bits */ flippin_bits = FlipVertical(the_bits); if (flippin_bits != NULL) { bounds = (*flippin_bits)->bounds; PlotMap(flippin_bits, 0, 0, srcCopy); KillBitMap(flippin_bits); } KillBitMap(the_bits); } notes: flippin! æKY FlipHorizontal æFc BitMap.h æMM æD BitMap* FlipHorizontal(BitMap* bits); æDT BitMap *horizontal_bits = FlipHorizontal((BitMap*) bits); æT Function æC ----- to flip a bitmap horizontally. arguments: bits a bitmap pointer return value: a newly created bitmap pointer containing the image from the bitmap pointer parameter flipped horizontally. if an error occurs, FlipVertical will return the value NULL. description: FlipHorizontal creates a new bitmap containing the image stored in the parameter bitmap pointer flipped horizontally. The resulting bitmap will be the same size as the original image. example application: The example creates a new bitmap pointer containing the image stored in the original bitmap flipped horizontally before copying the new flipped image to the current grafport. { BitMap *the_bits; BitMap *flippin_bits; Rect bounds; the_bits = NewBitMap(100, 200); if (the_bits != NULL) { /* here we would draw something into the_bits */ flippin_bits = FlipHorizontal(the_bits); if (flippin_bits != NULL) { bounds = (*flippin_bits)->bounds; PlotMap(flippin_bits, 0, 0, srcCopy); KillBitMap(flippin_bits); } KillBitMap(the_bits); } notes: none. æKY RotateBitMap æFc BitMap.h æMM æD BitMap* RotateBitMap(BitMap* bits, short cx, short cy, float angle); æDT BitMap *round_bits = RotateBitMap((BitMap*) bits, (short) cx, (short) cy, (float) angle); æT Function æC ----- to rotate a bitmap to a specific angle. arguments: bits a bitmap pointer cx the horizontal center of rotation cy the vertical center of rotation angle the angle (in degrees) to rotate the image. both positive and negative values are ok. This is a floating point number. return value: a newly created bitmap pointer containing the image from the bitmap pointer parameter rotated around the center cx and cy angle degrees. if an error occurs, RotateBitMap will return the value NULL. description: RotateBitMap creates a new bitmap containing the image from the parameter bitmap pointer rotated angle degrees about the center (cx, cy). The resultant bitmap will have the same dimensions as the parameter bitmap regardless of the angle specified. example application: The example creates a new bitmap pointer containing the image stored in the original bitmap rotated 35.5 degrees to the right before copying the rotated image to the current grafport. { BitMap *the_bits; BitMap *round_bits; Rect bounds; the_bits = NewBitMap(100, 200); if (the_bits != NULL) { /* here we would draw something into the_bits */ round_bits = RotateBitMap(the_bits, 50, 100, 35.5); if (round_bits != NULL) { bounds = (*round_bits)->bounds; PlotMap(round_bits, 0, 0, srcCopy); KillBitMap(round_bits); } KillBitMap(the_bits); } notes: The 68k implementation of RotateBitMap has a speedy implementation built on top of the fixed math routines. For more information about fixed math refer to the Mathematical and Logical Utilities chapter of Inside Macintosh: Operating System Utilities. æKY DuplicateBitMap æFc BitMap.h æMM æD BitMap* DuplicateBitMap(BitMap* bits); æDT BitMap *bitmap_copy = DuplicateBitMap((BitMap*) bits); æT Function æC ----- to make a copy of a bitmap. arguments: bits a bitmap pointer return value: a newly created bitmap pointer containing an exact duplicate of the bitmap parameter. if an error occurs, DuplicateBitMap will return the value NULL. description: DuplicateBitMap creates a copy of the bitmap parameter. example application: In this example, we make a new bitmap, duplicate it, and then dispose of the resulting bitmaps. { BitMap *the_bits; BitMap *other_bits; the_bits = NewBitMap(100, 200); if (the_bits != NULL) { other_bits = DuplicateBitMap(the_bits); if (other_bits != NULL) { KillBitMap(other_bits); } KillBitMap(the_bits); } notes: none. æKY PaintBucketBitMap æFc BitMap.h æMM æD BitMap* PaintBucketBitMap(BitMap* bits, short h, short v); æDT BitMap *painted_bits = PaintBucketBitMap((BitMap*) bits, (short) h, (short) v); æT Function æC ----- to create a paint bucket type mask for a bitmap. arguments: bits a bitmap pointer h the horizontal position to start painting v the vertical position to start painting return value: a newly created bitmap pointer containing an ones in every pixel where paint would not leak out starting from the point (h, v). if an error occurs, PaintBucketBitMap will return the value NULL. description: PaintBucketBitMap works like the paint bucket tool found in most graphical applications. It calls the routine SeedFill and to fill in the image information in the resulting bitmap pointer. example application: In this example, we make a new bitmap and create a mask bitmap using the PaintBucketBitMap routine starting at the point (50,50). { BitMap *the_bits; BitMap *paint_bits; the_bits = NewBitMap(100, 200); if (the_bits != NULL) { /* here, we would normally draw something in the bitmap */ paint_bits = PaintBucketBitMap(the_bits, 50, 50); if (paint_bits != NULL) { KillBitMap(paint_bits); } KillBitMap(the_bits); } notes: PaintBucketBitMap calls SeedFill. For further information about SeedFill refer to page 3-109 in the QuickDraw Drawing chapter of Inside Macintosh: Imaging With QuickDraw. æKY LassoBitMap æFc BitMap.h æMM æD BitMap* LassoBitMap(BitMap* bits); æDT BitMap *lassod_bits = LassoBitMap((BitMap*) bits); æT Function æC ----- to create a lasso'd mask of a bitmap. arguments: bits a bitmap pointer return value: a newly created bitmap pointer containing an ones in every pixel where paint would not leak in from the edges of the bitmap. if an error occurs, LassoBitMap will return the value NULL. description: LassoBitMap works like the lasso bucket tool found in most graphical applications. It calls the routine CalcMask and to fill in the image information in the resulting bitmap pointer. example application: In this example, we make a new bitmap and create a mask bitmap using the LassoBitMap routine. { BitMap *the_bits; BitMap *paint_bits; the_bits = NewBitMap(100, 200); if (the_bits != NULL) { /* here, we would normally draw something in the bitmap */ paint_bits = LassoBitMap(the_bits); if (paint_bits != NULL) { KillBitMap(paint_bits); } KillBitMap(the_bits); } notes: LassoBitMap calls CalcMask. For further information about CalcMask refer to page 3-111 in the QuickDraw Drawing chapter of Inside Macintosh: Imaging With QuickDraw. æKY TraceBitMap æFc BitMap.h æMM æD BitMap* TraceBitMap(BitMap* bits); æDT BitMap *traced_bits = TraceBitMap((BitMap*) bits); æT Function æC ----- to create a traced edges version of the bitmap. arguments: bits a bitmap pointer return value: a newly created bitmap pointer containing containing the original image with the edges traced. if an error occurs, TraceBitMap will return the value NULL. description: TraceBitMap performs the 'trace edges' command found in many graphical applications returning a new bitmap containing the traced image.. example application: In this example, we make a new bitmap and create a new bitmap containing the traced image. { BitMap *the_bits; BitMap *traced_bits; the_bits = NewBitMap(100, 200); if (the_bits != NULL) { /* here, we would normally draw something in the bitmap */ traced_bits = TraceBitMap(the_bits); if (traced_bits != NULL) { KillBitMap(traced_bits); } KillBitMap(the_bits); } notes: none. æKY EqualBitMaps æFc BitMap.h æMM æD Boolean EqualBitMaps(BitMap* a, BitMap* b); æDT Boolean is_equal = EqualBitMaps((BitMap*) a, (BitMap*) b); æT Function æC ----- compares two bitmaps for equality. arguments: a a bitmap pointer b a bitmap pointer return value: true or false. description: returns true if the two bitmaps are the same size and contain the same image content. returns false if either bitmap is NULL. example application: In this example, we make a new bitmap and create a two bitmaps and compare them by calling EqualBitMaps. { BitMap *the_bits; BitMap *other_bits; the_bits = NewBitMap(100, 200); if (the_bits != NULL) { other_bits = TraceBitMap(the_bits); if (other_bits != NULL) { /* here, we would normally draw something in the bitmaps */ if (EqualBitMaps(other_bits, the_bits)) { /* they're the same *blink* */ } KillBitMap(other_bits); } KillBitMap(the_bits); } notes: EqualBitMaps takes into account that either bitmap may have different rowBytes values, and the possibility that garbage values may be stored in the unused bits off to the right of the boundary rectangle. æKY PICTToBitMap æFc BitMap.h æMM æD BitMap* PICTToBitMap(PicHandle pic); æDT BitMap *picture_bits = PICTToBitMap((PicHandle) pic); æT Function æC ----- to convert a QuickDraw Picture into a bitmap pointer. arguments: pic a handle to a QuickDraw picture return value: a newly created bitmap pointer containing a black and white representation of the image drawn by the quickdraw picture parameter. if an error occurs, PICTToBitMap will return the value NULL. description: PICTToBitMap creates a new bitmap pointer the using the size information provided in the QuickDraw picture handle parameter and draws the picture in the bitmap before returning the bitmap. example application: In this example, we call GetPicture to retrieve a picture from a resource file and then we convert it to a bitmap by calling the routine PICTToBitMap. { PicHandle the_picture; BitMap *the_bits; the_picture = GetPicture(128); if (the_picture != NULL) { the_bits = PICTToBitMap(the_picture); if (the_bits != NULL) { /* at this point, the the_bits contains the picture */ KillBitMap(the_bits); } } notes: none. æKY BitMapToPICT æFc BitMap.h æMM æD PicHandle BitMapToPICT(BitMap* bits); æDT PicHandle the_picture = BitMapToPICT((BitMap*) bits); æT Function æC ----- to convert a bitmap pointer into a QuickDraw Picture. arguments: bits a bitmap pointer return value: a handle to a QuickDraw picture. if an error occurs, the picture's picFrame will be an empty rectangle. description: BitMapToPICT returns a QuickDraw picture that will draw the image stored in the bitmap. BitMapToPICT is the inverse of PICTToBitMap. example application: In this example, we create a bitmap and convert it into a QuickDraw picture. { PicHandle the_picture; BitMap *the_bits; the_bits = NewBitMap(100, 200); if (the_bits != NULL) { the_picture = BitMapToPICT(the_bits); KillBitMap(the_bits); } notes: QuickDraw pictures are a good way to store image data. æKY BitMapAND æFc BitMap.h æMM æD BitMap* BitMapAND(BitMap* a, BitMap* b); æDT BitMap *anded_bits = BitMapAND((BitMap*) a, (BitMap*) b); æT Function æC ----- to logically AND the raster data from two bitmaps. arguments: a a bitmap pointer b a bitmap pointer return value: a bitmap pointer containing the logical result of ANDing the raster data from bitmap a with the raster data from bitmap b. if an error occurs, NULL is returned. description: BitMapAND logically ANDs the raster data of two bitmap pointers returning a new bitmap pointer containing the result. The two parameter bitmaps must have identical dimensions. example application: In this example, we create two bitmaps and AND them together creating a third bitmap. { BitMap *a=NULL, *b=NULL, *c=NULL; a = NewBitMap(100, 100); if (a == NULL) goto my_error_handler; b = NewBitMap(100, 100); if (b == NULL) goto my_error_handler; c = BitMapAND(a, b); if (c == NULL) goto my_error_handler; /* at this point, c contains the result of logically ANDing the bitmaps a and b */ my_error_handler: if (a != NULL) KillBitMap(a); if (b != NULL) KillBitMap(b); if (c != NULL) KillBitMap(c); } notes: useful for calculating the intersection of two sets of bits. æKY BitMapOR æFc BitMap.h æMM æD BitMap* BitMapOR(BitMap* a, BitMap* b); æDT BitMap *ored_bits = BitMapOR((BitMap*) a, (BitMap*) b); æT Function æC ----- to logically OR the raster data from two bitmaps. arguments: a a bitmap pointer b a bitmap pointer return value: a bitmap pointer containing the logical result of ORing the raster data from bitmap a with the raster data from bitmap b. if an error occurs, NULL is returned. description: BitMapOR logically ORs the raster data of two bitmap pointers returning a new bitmap pointer containing the result. The two parameter bitmaps must have identical dimensions. example application: In this example, we create two bitmaps and OR them together creating a third bitmap. { BitMap *a=NULL, *b=NULL, *c=NULL; a = NewBitMap(100, 100); if (a == NULL) goto my_error_handler; b = NewBitMap(100, 100); if (b == NULL) goto my_error_handler; c = BitMapOR(a, b); if (c == NULL) goto my_error_handler; /* at this point, c contains the result of logically ORing the bitmaps a and b */ my_error_handler: if (a != NULL) KillBitMap(a); if (b != NULL) KillBitMap(b); if (c != NULL) KillBitMap(c); } notes: useful for calculating the union of two sets of bits. æKY BitMapXOR æFc BitMap.h æMM æD BitMap* BitMapXOR(BitMap* a, BitMap* b); æDT BitMap *xored_bits = BitMapXOR((BitMap*) a, (BitMap*) b); æT Function æC ----- to logically XOR the raster data from two bitmaps. arguments: a a bitmap pointer b a bitmap pointer return value: a bitmap pointer containing the logical result of XORing the raster data from bitmap a with the raster data from bitmap b. if an error occurs, NULL is returned. description: BitMapXOR logically XORs the raster data of two bitmap pointers returning a new bitmap pointer containing the result. The two parameter bitmaps must have identical dimensions. example application: In this example, we create two bitmaps and XOR them together creating a third bitmap. { BitMap *a=NULL, *b=NULL, *c=NULL; a = NewBitMap(100, 100); if (a == NULL) goto my_error_handler; b = NewBitMap(100, 100); if (b == NULL) goto my_error_handler; c = BitMapXOR(a, b); if (c == NULL) goto my_error_handler; /* at this point, c contains the result of logically XORing the bitmaps a and b */ my_error_handler: if (a != NULL) KillBitMap(a); if (b != NULL) KillBitMap(b); if (c != NULL) KillBitMap(c); } notes: useful for calculating the difference of two sets of bits. æKY BitMapNOT æFc BitMap.h æMM æD BitMap* BitMapNOT(BitMap* a); æDT BitMap *angry_bits = BitMapNOT((BitMap*) a); æT Function æC ----- complement a bitmap. arguments: a a bitmap pointer return value: a bitmap pointer containing the logical result of complementing the raster data from bitmap a. if an error occurs, NULL is returned. description: BitMapNOT returns a new bitmap pointer containing the inverse of the raster image contained in the bitmap pointer a. example application: In this example, we create a bitmap and it's complement. { BitMap *a=NULL, *b=NULL; a = NewBitMap(100, 100); if (a == NULL) goto my_error_handler; b = BitMapNOT(a); if (b == NULL) goto my_error_handler; /* at this point, b contains the compliment of a */ my_error_handler: if (a != NULL) KillBitMap(a); if (b != NULL) KillBitMap(b); } notes: useful for calculating the complement of a set of bits. æKY BitMapTest æFc BitMap.h æD Boolean BitMapTest(BitMap* bits, short h, short v); æDT Boolean pixel_value = BitMapTest((BitMap*) bits, (short) h, (short) v); æT Function æC ----- test the value of a particular pixel in a bitmap. arguments: bits a bitmap pointer h the horizontal position of the pixel to test v the vertical position of the pixel to test return value: true if the pixel is 1, false if the pixel is 0. description: BitMapTest tests the value of the pixel at the location (h,v) returning true if the pixel is 1, and false if the pixel is zero. example application: In this example, we create a bitmap and test the pixel located at (25, 32). { BitMap *bits=NULL; bits = NewBitMap(100, 100); if (bits == NULL) goto my_error_handler; .... if (BitMapTest(bits, 25, 32)) { /* the pixel is 1 */ } else { /* the pixel is 0 */ } my_error_handler: if (bits != NULL) KillBitMap(bits); } notes: attempting to test a point outside of the bitmap's bounds will produce unpredictable results. æKY BitMapSet æFc BitMap.h æD void BitMapSet(BitMap* bits, short h, short v); æDT BitMapSet((BitMap*) bits, (short) h, (short) v); æT Procedure æC ----- set the value of a particular pixel. arguments: bits a bitmap pointer h the horizontal position of the pixel to set v the vertical position of the pixel to set return value: none. description: BitMapSet sets the value of the pixel at the location (h,v) to 1. example application: In this example, we create a bitmap and set the pixel located at (25, 32) to the value 1. { BitMap *bits=NULL; bits = NewBitMap(100, 100); if (bits == NULL) goto my_error_handler; .... BitMapSet(bits, 25, 32); my_error_handler: if (bits != NULL) KillBitMap(bits); } notes: attempting to set a point outside of the bitmap's bounds will produce unpredictable results and may even crash your computer by overwriting something important like the operating system or your program or something like that. æKY BitMapClear æFc BitMap.h æD void BitMapClear(BitMap* bits, short h, short v); æDT BitMapClear((BitMap*) bits, (short) h, (short) v); æT Procedure æC ----- clear the value of a particular pixel. arguments: bits a bitmap pointer h the horizontal position of the pixel to set v the vertical position of the pixel to set return value: none. description: BitMapClear clears the value of the pixel at the location (h,v) to 0. example application: In this example, we create a bitmap and set the pixel located at (25, 32) to the value 0. { BitMap *bits=NULL; bits = NewBitMap(100, 100); if (bits == NULL) goto my_error_handler; .... BitMapClear(bits, 25, 32); my_error_handler: if (bits != NULL) KillBitMap(bits); } notes: attempting to clear a point outside of the bitmap's bounds will produce unpredictable results and may even crash your computer by overwriting something important like the operating system or your program or something like that. æKY BitMapToggle æFc BitMap.h æD Boolean BitMapToggle(BitMap* bits, short h, short v); æDT Boolean new_value = BitMapToggle((BitMap*) bits, (short) h, (short) v); æT Procedure æC ----- invert the value of a particular pixel returning it's new value. arguments: bits a bitmap pointer h the horizontal position of the pixel to set v the vertical position of the pixel to set return value: a boolean value indicating the state of the pixel after the toggle operation. i.e. if the pixel is set to the value 1, true is returned. If the pixel is set to the value 0, false is returned. description: BitMapToggle inverts the value of the pixel at the location (h,v) returning true if the pixel is set to 1 or false if the pixel is set to 0. example application: In this example, we create a bitmap and invert the pixel located at (25, 32). { BitMap *bits=NULL; bits = NewBitMap(100, 100); if (bits == NULL) goto my_error_handler; .... BitMapToggle(bits, 25, 32); my_error_handler: if (bits != NULL) KillBitMap(bits); } notes: attempting to toggle a point outside of the bitmap's bounds will produce unpredictable results and may even crash your computer by overwriting something important like the operating system or your program or something like that. æKY NewBMP æFc BitMap.h æMM æD BitMapPort* NewBMP(BitMap* bits); æDT BitMapPort *bmp = NewBMP((BitMap*) bits); æT Function æC ----- set up a drawing environment for drawing into a bitmap. arguments: bits a bitmap pointer return value: a pointer to a BitMapPort data structure. if an error occurs, NULL is returned. description: NewBMP is called by the WithBitMap macro and you should never have to call it directly yourself. What it does is it saves the original grafport, and creates a new grafport suitable for drawing into the bitmap. NewBMP should be followed by a call to DisposeBMP which will restore the original grafport, unlock the bitmap, and dispose of the new grafport. example application: In this example, we create a bitmap and use the NewBMP to make a grafport. Then we draw into it and call DisposeBMP to deallocate the grafport. { BitMap *bits=NULL; BitMapPort *bmp=NULL; bits = NewBitMap(100, 100); if (bits == NULL) goto my_error_handler; bmp = NewBMP(bits); if (bmp == NULL) goto my_error_handler; /* after NewBMP, the grafport is set to draw into the bitmap */ MoveTo(10,10); LineTo(20,20); DrawString("\pHello World"); my_error_handler: if (bmp != NULL) DisposeBMP(bmp); if (bits != NULL) KillBitMap(bits); } notes: if NewBMP returns a pointer to a BitMapPort, then you must dispose of that pointer with a call to DisposeBMP. æKY DisposeBMP æFc BitMap.h æMM æD void DisposeBMP(BitMapPort* bmp); æDT DisposeBMP((BitMapPort*) bmp); æT Procedure æC ----- dispose of a drawing enviroment created by NewBMP and restore the previous drawing environment. arguments: bmp a pointer to a BitMapPort structure allocated by NewBMP return value: none. description: DisposeBMP restores the original grafport and, deallocates the grafport allocated for drawing into the bitmap. The macro WithBitMap calls this routine automatically and you will not normally have to call it directly. example application: see the example in NewBMP. notes: none. æKY WithBitMap æFc BitMap.h æMM æD #define WithBitMap(bits, bmp) æDT WithBitMap(((BitMap*) bits), ((BitMapPort*) bmp)) { statement... } æT Macro æC ----- execute a statement while the drawing environment is set up to draw into the bitmap. arguments: bits a bitmap pointer bmp a variable you have declared of type BitMapPort* return value: not applicable description: WithBitMap is a macro facility that sets up the drawing environment such that any drawing commands in the statement following the macro instantiation will draw into the bitmap provided as the first parameter. example application: In this example, we create a bitmap and use the WithBitMap macro to do some drawing in it. { BitMap *bits=NULL; BitMapPort *bmp; bits = NewBitMap(100, 100); if (bits == NULL) goto my_error_handler; WithBitMap(bits, bmp) { MoveTo(10,10); LineTo(20,20); TextFont(geneva); TextSize(12); DrawString("\pHello World"); } my_error_handler: if (bits != NULL) KillBitMap(bits); } notes: WithBitMap macros can be nested, however if you do this you must provide a different variable of type (BitMapPort *) for each instantiation. æKY PlotBitMap æFc BitMap.h æMM æD void PlotBitMap(BitMap* bits, short h, short v); æDT PlotBitMap((BitMap*) bits, (short) h, (short) v); æT Procedure æC ----- for creating a new bitmap pointer. arguments: bits a bitmap pointer h the horizontal location where the bitmap is drawn v the horizontal location where the bitmap is drawn mode transfer mode passed to copybits return value: none. description: PlotBitMap provides a simple interface for drawing a bitmap in the current grafport. The bitmap is drawn with the top left corner aligned with the point (h,v) using the indicated transfer mode. In this example, we create a bitmap and use the WithBitMap macro to do some drawing in it, and then we copy the result to the current grafport at the location (75, 23) using the PlotBitMap routine. { BitMap *bits=NULL; BitMapPort *bmp; bits = NewBitMap(100, 100); if (bits == NULL) goto my_error_handler; WithBitMap(bits, bmp) { MoveTo(10,10); TextFont(geneva); TextSize(12); DrawString("\pHello World"); } PlotBitMap(bits, 75, 23, srcCopy); my_error_handler: if (bits != NULL) KillBitMap(bits); } notes: PlotBitMap calls CopyBits. æKY BitMapPort æFc BitMap.h æT structure æD typedef struct { GrafPort gp; /* the grafport record for drawing into the bitmap */ GrafPtr gpsave; /* saved grafport for later restoration */ BitMap* bits; /* the bitmap handle */ } BitMapPort; æC ----- BitMapPort data structure managed by the routines NewBMP and DisposeBMP. You should never have to access the fields of this record directly as it's all taken care of by NewBMP and DisposeBMP.